<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
 <head>
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  <title>The MongoWriteBatch class</title>
<link media="all" rel="stylesheet" type="text/css" href="styles/03e73060321a0a848018724a6c83de7f-theme-base.css" />
<link media="all" rel="stylesheet" type="text/css" href="styles/03e73060321a0a848018724a6c83de7f-theme-medium.css" />

 </head>
 <body class="docs"><div class="navbar navbar-fixed-top">
  <div class="navbar-inner clearfix">
    <ul class="nav" style="width: 100%">
      <li style="float: left;"><a href="mongo.batch.html">« Batch Classes</a></li>
      <li style="float: right;"><a href="mongowritebatch.add.html">MongoWriteBatch::add »</a></li>
    </ul>
  </div>
</div>
<div id="breadcrumbs" class="clearfix">
  <ul class="breadcrumbs-container">
    <li><a href="index.html">PHP Manual</a></li>
    <li><a href="mongo.batch.html">Batch Classes</a></li>
    <li>The MongoWriteBatch class</li>
  </ul>
</div>
<div id="layout">
  <div id="layout-content"><div id="class.mongowritebatch" class="reference">

 <h1 class="title">The MongoWriteBatch class</h1>
 

 <div class="partintro"><p class="verinfo">(PECL mongo &gt;=1.5.0)</p>


  <div class="section" id="mongowritebatch.intro">
   <h2 class="title">Introduction</h2>
   <p class="para">
    MongoWriteBatch is the base class for the <a href="class.mongoinsertbatch.html" class="classname">MongoInsertBatch</a>,
    <a href="class.mongoupdatebatch.html" class="classname">MongoUpdateBatch</a> and <a href="class.mongodeletebatch.html" class="classname">MongoDeleteBatch</a> classes.
   </p>
   <p class="para">
    MongoWriteBatch allows you to &quot;batch up&quot; multiple operations (of same type) and shipping them all
    to MongoDB at the same time. This can be especially useful when operating on many documents at the
    same time to reduce roundtrips.
   </p>
   <p class="para">
    Prior to version 1.5.0 of the driver it was possible to use <span class="methodname"><a href="mongocollection.batchinsert.html" class="methodname">MongoCollection::batchInsert()</a></span>,
    however, as of 1.5.0 that method is now discouraged.
   </p>
   <p class="para">
    Note: This class is only available when talking to MongoDB 2.6.0 (and later) servers. It will throw
    <a href="class.mongoprotocolexception.html" class="classname">MongoProtocolException</a> if attempting to use it on older MongoDB servers.
   </p>
  </div>


  <div class="section" id="mongowritebatch.synopsis">
   <h2 class="title">Class synopsis</h2>


   <div class="classsynopsis">
    <div class="ooclass"></div>


    <div class="classsynopsisinfo">
     <span class="ooclass">
      <strong class="classname">MongoWriteBatch</strong>
     </span>
     {</div>

    
    <div class="classsynopsisinfo classsynopsisinfo_comment">/* Constants */</div>
    <div class="fieldsynopsis">
     <span class="modifier">const</span>
     <span class="type">int</span>
      <var class="fieldsynopsis_varname"><a href="class.mongowritebatch.html#mongowritebatch.constants.command.insert"><var class="varname">COMMAND_INSERT</var></a></var><span class="initializer"> = 1</span>
    ;</div>

    <div class="fieldsynopsis">
     <span class="modifier">const</span>
     <span class="type">int</span>
      <var class="fieldsynopsis_varname"><a href="class.mongowritebatch.html#mongowritebatch.constants.command.update"><var class="varname">COMMAND_UPDATE</var></a></var><span class="initializer"> = 2</span>
    ;</div>

    <div class="fieldsynopsis">
     <span class="modifier">const</span>
     <span class="type">int</span>
      <var class="fieldsynopsis_varname"><a href="class.mongowritebatch.html#mongowritebatch.constants.command.delete"><var class="varname">COMMAND_DELETE</var></a></var><span class="initializer"> = 3</span>
    ;</div>


    <div class="classsynopsisinfo classsynopsisinfo_comment">/* Methods */</div>
    <div class="constructorsynopsis dc-description">
   <span class="modifier">protected</span> <span class="methodname"><a href="mongowritebatch.construct.html" class="methodname">__construct</a></span>(<span class="methodparam"><span class="type"><a href="class.mongocollection.html" class="type MongoCollection">MongoCollection</a></span> <code class="parameter">$collection</code></span>, <span class="methodparam"><span class="type">string</span> <code class="parameter">$batch_type</code><span class="initializer"> = ?</span></span>, <span class="methodparam"><span class="type">array</span> <code class="parameter">$write_options</code><span class="initializer"> = ?</span></span>)</div>

    <div class="methodsynopsis dc-description"><span class="modifier">public</span> <span class="methodname"><a href="mongowritebatch.add.html" class="methodname">add</a></span>(<span class="methodparam"><span class="type">array</span> <code class="parameter">$item</code></span>): <span class="type">bool</span></div>
<div class="methodsynopsis dc-description"><span class="modifier">final</span> <span class="modifier">public</span> <span class="methodname"><a href="mongowritebatch.execute.html" class="methodname">execute</a></span>(<span class="methodparam"><span class="type">array</span> <code class="parameter">$write_options</code></span>): <span class="type">array</span></div>

   }</div>


   <div class="section" id="mongowritebatch.constants">
    <h2 class="title">MongoWriteBatch types</h2>
    <dl>


     
      <dt id="mongowritebatch.constants.command.insert"><strong><code>MongoWriteBatch::COMMAND_INSERT</code></strong></dt>

      <dd>

       <p class="para">Create an Insert Write Batch</p>
      </dd>

     

     
      <dt id="mongowritebatch.constants.command.update"><strong><code>MongoWriteBatch::COMMAND_UPDATE</code></strong></dt>

      <dd>

       <p class="para">Create an Update Write Batch</p>
      </dd>

     

     
      <dt id="mongowritebatch.constants.command.delete"><strong><code>MongoWriteBatch::COMMAND_DELETE</code></strong></dt>

      <dd>

       <p class="para">Create an Delete Write Batch</p>
      </dd>

     

    </dl>

   </div>
  </div>

  <div class="section" id="mongowritebatch.description">
   <h2 class="title">Description</h2>
   <p class="para">
    When executing a batch by calling
    <span class="methodname"><a href="mongowritebatch.execute.html" class="methodname">MongoWriteBatch::execute()</a></span>, MongoWriteBatch will send
    up to <code class="literal">maxWriteBatchSize</code> (defaults to 1000) documents or
    <code class="literal">maxBsonObjectSize</code> (defaults to 16777216 bytes), whichever
    comes first.
   </p>
   <blockquote class="note"><p><strong class="note">Note</strong>: 
    <p class="para">
     Documents will never be partially transferred. When adding documents to the batch, that overflows the limit, a new
     batch will be created and the document put into the new batch.
    </p>
   </p></blockquote>
  </div>

  <div class="section" id="mongowritebatch.errors">
   <h2 class="title">Errors/Exceptions</h2>
   <ul class="simplelist">
    <li class="member"><strong class="classname">Exception</strong> on parameter parsing failures</li>
    <li class="member"><strong class="classname">Exception</strong> on argument validation errors (e.g. missing keys)</li>
    <li class="member"><a href="class.mongoprotocolexception.html" class="classname">MongoProtocolException</a> when talking to MongoDB server older then 2.6.0.</li>
    <li class="member"><a href="class.mongoprotocolexception.html" class="classname">MongoProtocolException</a> on socket errors.</li>
    <li class="member"><a href="class.mongowriteconcernexception.html" class="classname">MongoWriteConcernException</a> when a write fails due to <a href="mongo.writeconcerns.html" class="link">WriteConcerns</a></li>
   </ul>
  </div>

  <div class="section" id="mongowritebatch.examples">
   <h2 class="title">Examples</h2>
   <div class="example" id="mongowritebatch.example.basic">
    <p><strong>Example #1 <strong class="classname">MongoWriteBatch</strong> example</strong></p>
    <div class="example-contents"><p>
     Adding documents to a Insert batch and then execute it
    </p></div>
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />$mc&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">MongoClient</span><span style="color: #007700">(</span><span style="color: #DD0000">"localhost"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$collection&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$mc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">selectCollection</span><span style="color: #007700">(</span><span style="color: #DD0000">"test"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"test"</span><span style="color: #007700">);<br /><br /><br /></span><span style="color: #0000BB">$docs&nbsp;</span><span style="color: #007700">=&nbsp;array();<br /></span><span style="color: #0000BB">$docs</span><span style="color: #007700">[]&nbsp;=&nbsp;array(</span><span style="color: #DD0000">"my"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">"demo"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$docs</span><span style="color: #007700">[]&nbsp;=&nbsp;array(</span><span style="color: #DD0000">"is"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">"working"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$docs</span><span style="color: #007700">[]&nbsp;=&nbsp;array(</span><span style="color: #DD0000">"pretty"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">"well"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$batch&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">MongoInsertBatch</span><span style="color: #007700">(</span><span style="color: #0000BB">$collection</span><span style="color: #007700">);<br />foreach(</span><span style="color: #0000BB">$docs&nbsp;</span><span style="color: #007700">as&nbsp;</span><span style="color: #0000BB">$document</span><span style="color: #007700">)&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$batch</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">add</span><span style="color: #007700">(</span><span style="color: #0000BB">$document</span><span style="color: #007700">);<br />}<br /></span><span style="color: #0000BB">$retval&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$batch</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">execute</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"w"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">1</span><span style="color: #007700">));<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$retval</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

    <div class="example-contents"><p>The above example will output:</p></div>
    <div class="example-contents screen">
<div class="cdata"><pre>
array(2) {
  [&quot;nInserted&quot;]=&gt;
  int(3)
  [&quot;ok&quot;]=&gt;
  bool(true)
}
</pre></div>
    </div>
   </div>
  </div>

 </div>

 














 







<h2>Table of Contents</h2><ul class="chunklist chunklist_reference"><li><a href="mongowritebatch.add.html">MongoWriteBatch::add</a> — Adds a write operation to a batch</li><li><a href="mongowritebatch.construct.html">MongoWriteBatch::__construct</a> — Creates a new batch of write operations</li><li><a href="mongowritebatch.execute.html">MongoWriteBatch::execute</a> — Executes a batch of write operations</li></ul>
</div>
</div></div></body></html>